home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1998 August: Tool Chest / Dev.CD Aug 98 TC.toast / Tool Chest / Testing & Debugging / Virtual User / Virtual User Current Release / Supplements / Assist Module for MacApp / Assist Module MA 2.0.1 / READ ME FIRST!
Encoding:
Text File  |  1998-06-04  |  7.9 KB  |  202 lines  |  [TEXT/MPS ]
  1. **************************************************************************
  2. VUAssist, The V.U. Assistance Module for MacApp Applications
  3. **************************************************************************
  4.  
  5. In order to find the location of items in windows for V.U., Agent VU peruses 
  6. the content list of windows and the item list of dialogs.  For applications 
  7. which are not built with MacApp, these data structures can be accessed via 
  8. global variables by Agent VU.  For MacApp applications, however, items in 
  9. windows are subclasses of the class TView, which are not available to the 
  10. Agent via global data structures.   As a result, Agent VU can’t provide any 
  11. information about these items to V.U. in the normal way.
  12.  
  13. To work around this problem, Agent VU provides a hook which allows an 
  14. application to assist Agent VU by providing information about itself.  
  15. In this folder, we’ve provided VUAssist, an assistance module for MacApp 
  16. applications which can be hooked onto Agent VU to provide information about 
  17. a MacApp application. A user can build a MacApp application with VUAssist 
  18. and then test the application with V.U..  V.U. will "recognize" many of the
  19. application's views which translate into standard user interface items: buttons,
  20. scroll bars, checkboxes, static text, editable text fields, popup menus, etc.
  21.  
  22. The module exists as a unit called UVUAssist.  The unit consists of four files:   
  23. VUAssist.p, VUAssist.inc1.p, VUAssist.inc2.p, and VUAssist.a.
  24.  
  25.  
  26. -----------------------------------------------------------------------------
  27. What's New in this Version, 1.0a1, since 1.0d11
  28. -----------------------------------------------------------------------------
  29.  
  30. 1) A bug having to do with menu selection and the gathering of state information
  31. about menus was fixed.  
  32.  
  33.  
  34. -----------------------------------------------------------------------------
  35. How to Use VUAssist
  36. -----------------------------------------------------------------------------
  37.  
  38. To build VUAssist into your MacApp application, follow the instructions
  39. below.  
  40.  
  41. For applications written in Object Pascal:
  42.  
  43. 1)  Modify your MAMake file to include the following:
  44.  
  45.     •    add the following to the list of OtherInterfaces
  46.         
  47.         "{SrcApp}UVUAssist.a" ∂
  48.         "{SrcApp}UVUAssist.p" ∂
  49.         
  50.     •    add the following to the list of OtherLinkFiles
  51.         
  52.         "{ObjApp}UVUAssist.a.o" ∂
  53.         "{ObjApp}UVUAssist.p.o" 
  54.     
  55.     •    add the additional dependency:
  56.  
  57.         "{ObjApp}UVUAssist.p.o"    ƒ ∂
  58.                     "{SrcApp}UVUAssist.p" ∂
  59.                     "{SrcApp}UVUAssist.inc1.p" ∂
  60.                     "{SrcApp}UVUAssist.inc2.p" ∂
  61.                     {MacAppIntf} ∂
  62.                     {BuildingBlocksIntf}
  63.                             
  64. 2)     Modify or subclass your descendant of TApplication to do the following:
  65.                             
  66.     •    In MyApplication.IApplication, you must execute this:
  67.             NEW(gVUAssist);
  68.             FailNil(gVUAssist);
  69.             gVUAssist.IVUAssist(gridItemSupport); { gridItemSupport must be a boolean 
  70.                                                     expression.  See "Altering the 
  71.                                                     behavior of VUAssist for an 
  72.                                                     explanation of gridItemSupport }
  73.             gVUAssist.SetIdleFreq(kVUAssistIdleFreq);
  74.             SELF.InstallCohandler(gVUAssist, true);
  75.  
  76.     •    In MyApplication.AboutToLoseControl you must execute this:
  77.             gVUAssist.SuspendMole;
  78.  
  79.     •    In MyApplication.RegainControl you must execute this:
  80.             gVUAssist.ResumeMole;
  81.  
  82.     •    In MyApplication.Close you must execute this BEFORE calling INHERITED Close:
  83.             SELF.InstallCohandler(gVUAssist,false);
  84.  
  85. 3)    Include the unit UVUAssist in your USES clause where appropriate.  Other units, 
  86.     such as UPrinting, UTEView, UDialog, and UGridView may need to be included along 
  87.     with UVUAssist if they are not already.
  88.  
  89.  
  90. For applications written in C++:
  91.  
  92. 1)  Modify your MAMake file to include the following:
  93.  
  94.     •    add the following to the list of OtherInterfaces
  95.         
  96.         "{SrcApp}UVUAssist.a" ∂
  97.         "{SrcApp}UVUAssist.p" ∂
  98.         "{SrcApp}UVUAssist.h"
  99.         
  100.     •    add the following to the list of OtherLinkFiles
  101.         
  102.         "{ObjApp}UVUAssist.a.o" ∂
  103.         "{ObjApp}UVUAssist.p.o" 
  104.     
  105.     •    add the additional dependency:
  106.  
  107.         "{ObjApp}UVUAssist.p.o"    ƒ ∂
  108.                     "{SrcApp}UVUAssist.p" ∂
  109.                     "{SrcApp}UVUAssist.inc1.p" ∂
  110.                     "{SrcApp}UVUAssist.inc2.p" ∂
  111.                     {MacAppIntf} ∂
  112.                     {BuildingBlocksIntf}
  113.                             
  114. 2)     Modify or subclass your descendant of TApplication to do the following:
  115.                             
  116.     •    In MyApplication.IApplication, you must execute this:
  117.             gVUAssist = new TVUAssist;
  118.             FailNIL(gVUAssist);
  119.             gVUAssist->IVUAssist(gridItemSupport); /* gridItemSupport must be a boolean 
  120.                                                     expression.  See "Altering the 
  121.                                                     behavior of VUAssist for an 
  122.                                                     explanation of gridItemSupport */
  123.             gVUAssist->SetIdleFreq(kVUAssistIdleFreq);
  124.             this->InstallCohandler(gVUAssist, true);
  125.  
  126.  
  127.     •    In MyApplication.AboutToLoseControl you must execute this:
  128.             gVUAssist->SuspendMole();
  129.  
  130.     •    In MyApplication.RegainControl you must execute this:
  131.             gVUAssist->ResumeMole();
  132.  
  133.     •    In MyApplication.Close you must execute this BEFORE calling INHERITED Close:
  134.             this->InstallCohandler(gVUAssist,false);
  135.  
  136. 3)    Include the header file UVUAssist.h where appropriate.
  137.  
  138.         #ifndef __UVUASSIST__
  139.         #include "UVUAssist.h"
  140.         #endif
  141.         
  142.  
  143. 4)    If you are using C++, make sure to use the VUAssist.a file which is included 
  144.     in the folder "C++ Interface to VUAssist" in place of the file with the same 
  145.     name which is found in the folder "VUAssist Source Code".
  146.  
  147.  
  148. -----------------------------------------------------------------------------
  149. Modifying the Behavior of VUAssist
  150. -----------------------------------------------------------------------------
  151.  
  152. 1) VUAssist Idle Frequency
  153.  
  154. VUAssist has now been defined to be a descendant of TEvtHandler (or TEventHandler 
  155. in MacApp 3.0).  An application's responsiveness to V.U. queries can be controlled 
  156. by setting the idle frequency of VUAssist. Although nothing is done with this idle 
  157. time, it forces the application to awaken and call SystemTask with the application's 
  158. context switched in.  This is necessary for Agent VU, a driver, to get processing 
  159. time.  Agent VU, in turn, calls VUAssist.  So, in a roundabout way, the application's 
  160. responsiveness to V.U. can be controlled by setting the idle frequency of VUAssist.
  161.  
  162. By default, the idle frequency of VUAssist has been set to 1, the near maximum 
  163. frequency. You may want to alter this by executing the following statement:
  164.  
  165. gVUAssist.SetIdleFreq(newIdleFreq);
  166.  
  167. Note, however, that larger values of VUAssist's idle frequency will slow down the 
  168. application's responsiveness to V.U. unless there is another cohandler with a very 
  169. high idle frequency.
  170.  
  171.  
  172. 2) The gridItemSupport Argument
  173.  
  174. Note that the TVUAssist method IVUAssist now takes an argument, gridItemSupport.  
  175. This argument, if true, enables an optional feature of VUAssist where the cells 
  176. of gridviews are recognized as individual user interface items by V.U..  Virtual 
  177. User does not yet have a gridview or list descriptor.  So, for the short term, 
  178. the "gridItemSupport" feature treats each cell of a gridview as a "contentitem" 
  179. in the V.U. scripting language.
  180.  
  181. In applications with very large gridviews, it may not be desirable to treat each 
  182. cell in a gridview as a separate item in V.U..  This may hamper performance.  By 
  183. setting the value of the gridItemSupport argument to false, you will disable V.U.'s 
  184. griditem support feature and the cells of gridviews will not be seen as 
  185. "contentItems" by V.U..  The cells will be "invisible" to Virtual User.
  186.  
  187. **** WARNING!! *******************************************************************
  188. If the "gridItemSupport" feature is enabled, the following rules MUST be followed:
  189.  
  190. 1) Any descendants of TTextGridView in your application MUST override the method 
  191. TTextGridView.GetText.  This method is called by VUAssist to obtain the text 
  192. associated with a gridview cell. TTextGridView.GetText is a method which must be 
  193. overridden in MacApp. 
  194.  
  195. 2) For reasons analogous to those above, any descendants of TTextListView in your 
  196. application MUST override the method TTextListView.GetItemText.  
  197. TTextListView.GetText need not be overridden.
  198. ***********************************************************************************
  199.  
  200.  
  201.  
  202.